The OPC Studio application component allows management of OPC UA client or server application. The OPC UA Application component has high-level properties and methods for tasks related to maintaining application registrations in the GDS servers, obtaining instance certificate from GDS, refreshing application trust lists from GDS, and similar tasks.

The OPC UA Application component is implemented by the EasyUAApplication Class, which you can access from your code, or (in project types that support it) drag from Visual Studio Toolbox to your form, control or component, and configure its properties there. Alternatively, most of the functionality provided by the OPC UA Application component is also accessible via the OPC UA Client-Server Application Service, which you can use in code places where you only want to have a dependency on the IEasyUAClient Interface.

In Windows desktop applications, you can also use the EasyUAFormsApplication Class, which derives from EasyUAApplication, and extends it by providing user interface capabilities for work with the OPC UA application. For more information, see "Windows Desktop Applications" further below.

If you can, prefer use of the OPC UA Application component over implementing the same functionality yourself, e.g. with the help of OPC UA Global Discovery Client and/or OPC UA Certificate Management Client. The OPC UA Application component already has all the necessary logic needed to perform the typical client-side application tasks properly and easily.

Specifically, methods in this component that work with the Global Discovery Server (GDS) or Certificate manager (CM) are not licensed for use in lower editions of QuickOPC.

Managing Instance Certificate

Getting Certificate Subject Name

In order to get the subject distinguished name the application is configured to use for its certificates, call the GetCertificateSubjectName Method.

The value returned is implementation-dependent. For the OPC UA Application component, and OPC UA Client-Server Application Service on the EasyUAClient Class implemented with the OPC Foundation's UA SDK, it is determined by the settings in the UAClientServerApplicationParameters Class, as described here: Providing OPC UA Application Instance Certificate.

For an example to this method, see: Examples - OPC UA Application - Get certificate subject name .

Finding (Getting) Own Certificate

In order to get the instance certificate the application is currently configured to use, call the FindOwnCertificate Method.

The method returns the instance certificate, if found. It returns null if the instance certificate cannot be found.

Validating Own Certificate

In order to validate the instance certificate the application is currently configured to use, call the ValidateOwnCertificate Method.

Creating Own Certificate

In order to create the instance certificate the application is currently configured to use, call the CreateOwnCertificate Method. It is possible to specify whether the instance certificate must not be present prior to the operation, or whether the operation will be able to replace it.

Using the UpdateTrustedPeerCertificates Property (defaults to true), you can control whether the trusted peers certificate store will also be updated.

Note that by default, QuickOPC creates the own application certificate automatically. For details, see Providing OPC UA Application Instance Certificate.

Removing Own Certificate. 

In order to remove the instance certificate the application is currently configured to use, call the RemoveOwnCertificate Method. If you are using multiple certificates with distinct certificate sub-id (see further below), you can specify the sub-id of the certificate to be removed. There is also an RemoveOwnCertificates Method (notice the plural in the name) which removes all application certificates whose sub-id conforms to the specified pattern. You can use e.g. "*"  as a pattern to remove certificates with any sub-id.

The return value of the method indicates whether the certificate has been removed.

When the application instance certificate is removed, its copies in the trusted peers certificate store, if any, are removed as well. This behavior is turned by default, but it is optional; there is an overload of the method that allows you to pass in a corresponding flag.

.NET

// Shows how to remove the own application certificate.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    class RemoveOwnCertificate
    {
        public static void Main1()
        {
            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;

            try
            {
                Console.WriteLine("Removing the own application certificate...");
                application.RemoveOwnCertificate();
                Console.WriteLine("The application certificate has been removed.");
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
            }
        }
    }
}

Assuring Own Certificate

In order to assure presence of the instance certificate the application is currently configured to use, call the AssureOwnCertificate Method. If the instance certificate does not exist in the certificate store prior to the operation, the method creates it. Otherwise, the method also checks whether the instance certificate is present in the trusted peers certificate store, and if it is absent, it copies it there; it then validates the certificate.

If you use OPC UA with self-signed certificates, a common way to verify that the other communication party has the right certificate (i.e. that of your application) is to check whether the thumbprint of the certificate (essentially, its hash) to be trusted on the other side is the same as yours. The following example can be used to first assure the existence of the client application certificate (and create it if not present yet), and display its thumbprint so that it can be used for verification on the other side of the communication (OPC UA server).

.NET

// Shows how to assure presence of the own application certificate, and display its thumbprint.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.BaseLib.Security.Cryptography.PkiCertificates;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    class AssureOwnCertificate
    {
        public static void Main1()
        {
            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;
            
            try
            {
                Console.WriteLine("Assuring presence of the own application certificate...");
                bool created = application.AssureOwnCertificate();

                Console.WriteLine(created
                    ? "A new certificate has been created."
                    : "An existing certificate has been found.");

                Console.WriteLine();
                Console.WriteLine("Finding the current application certificate...");
                IPkiCertificate pkiCertificate = application.FindOwnCertificate();

                Console.WriteLine();
                Console.WriteLine($"The thumbprint of the current application certificate is: {pkiCertificate?.Thumbprint}");
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }
        }
    }
}

' Shows how to assure presence of the own application certificate, and display its thumbprint.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.BaseLib.Security.Cryptography.PkiCertificates
Imports OpcLabs.EasyOpc.UA.Application
Imports OpcLabs.EasyOpc.UA.Application.Extensions
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Application._IEasyUAClientServerApplication
    Friend Class AssureOwnCertificate
        Public Shared Sub Main1()
            ' Obtain the application interface.
            Dim application As EasyUAApplication = EasyUAApplication.Instance

            Try
                Console.WriteLine("Assuring presence of the own application certificate...")
                Dim created As Boolean = application.AssureOwnCertificate()

                Console.WriteLine(If(created,
                                  "A new certificate has been created.",
                                  "An existing certificate has been found."))

                Console.WriteLine()
                Console.WriteLine("Finding the current application certificate...")
                Dim pkiCertificate As IPkiCertificate = application.FindOwnCertificate()

                Console.WriteLine()
                Console.WriteLine($"The thumbprint of the current application certificate is: {pkiCertificate?.Thumbprint}")
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try
        End Sub
    End Class
End Namespace

Python

# Shows how to assure presence of the own application certificate, and display its thumbprint.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Application import *
from OpcLabs.EasyOpc.UA.Application.Extensions import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Obtain the application interface.
application = EasyUAApplication.Instance

try:
    print('Assuring presence of the own application certificate...')
    created = IEasyUAClientServerApplicationExtension.AssureOwnCertificate(application)

    print('A new certificate has been created.' if created else 'An existing certificate has been found.')

    print()
    print('Finding the current application certificate...')
    pkiCertificate = IEasyUAClientServerApplicationExtension.FindOwnCertificate(application)

    print()
    print('The thumbprint of the current application certificate is: ',
          None if pkiCertificate is None else pkiCertificate.Thumbprint,
          sep='')
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

print()
print('Finished.')

Importing Own Certificate

In order to import the own certificate and its private key from a file, use the ImportOwnCertificateFromFile Method.

Exporting Own Certificate

In order export the own certificate and optionally its private to a given file, use the ExportOwnCertificateToFile Method.

Exporting the Application

In order to export the registration data of the OPC UA application into an  XML file, call the ExportRegisteredApplication Method. This method exports the security settings in the format used by the GDS client from OPC Foundation (Windows desktop sample). It uses the RegisteredApplication schema (which is not part of the OPC UA standard).

In order to export the security settings of the OPC UA application into an XML file, call the ExportSecuredApplication Method. This method exports the security settings in the format described in OPC UA Specification Part 6, Annex "Security settings management". The file conforms to the SecuredApplication schema.

Managing GDS Registrations

The OPC UA Application component is capable of maintaining client application registrations with one or more GDS servers simultaneously. The methods described further below allow you to control these registrations.

The component keeps track of the registrations (and un-registrations) performed. You can use the ApplicationIdDictionary Property to figure out the application IDs assigned to the current client application by the OPC UA Global Discovery Servers.

Registering to GDS

In order to register the current client application with the OPC UA Global Discovery Server (GDS), call the RegisterToGds Method. This method creates an application registration in the GDS, assigning it a new application ID. Existing registrations with the same application URI are removed first.

The difference between the RegisterToGds and UpdateGdsRegistration methods is that the RegisterToGds Method always obtains a new application ID, whereas the UpdateGdsRegistration Method attempts to reuse the existing application ID, if known. Neither of these methods requires the GDS registration be in any particular state for it to succeed, and both methods assure that after a successful execution, there is one and only one registration in the given GDS for this application.

The identity of the application itself is carried by its application URI, as given by the ApplicationUriString returned by the GetApplicationElement Method. Methods on this interface that manipulate or inspect the GDS registration use the application URI to identify the registration records belonging to this application.

For an example to this method, see: Examples - OPC UA Application - Register to GDS.

Updating GDS Registration

In order to update the registration of the current client application within the OPC UA Global Discovery Server (GDS), call the UpdateGdsRegistration Method. This method updates an application registration in the GDS, keeping its application ID. A new registration is created if the application is not yet registered in the GDS. Preexisting registrations with the same application URI are removed.

The difference between the RegisterToGds and UpdateGdsRegistration methods is that the RegisterToGds Method always obtains a new application ID, whereas the UpdateGdsRegistration Method attempts to reuse the existing application ID, if known. Neither of these methods requires the GDS registration be in any particular state for it to succeed, and both methods assure that after a successful execution, there is one and only one registration in the given GDS for this application.

The identity of the application itself is carried by its application URI, as given by the ApplicationUriString returned by the GetApplicationElement Method. Methods on this interface that manipulate or inspect the GDS registration use the application URI to identify the registration records belonging to this application.

.NET

// Shows how to update an application registration in the GDS, keeping its application ID if possible.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.AddressSpace;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.Extensions;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    class UpdateGdsRegistration
    {
        public static void Main1()
        {
            // Define which GDS we will work with.
            UAEndpointDescriptor gdsEndpointDescriptor =
                ((UAEndpointDescriptor)"opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer")
                .WithUserNameIdentity("appadmin", "demo");

            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;

            // Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString);

            // Update an application registration in the GDS, keeping its application ID if possible.
            UANodeId applicationId;
            try
            {
                applicationId = application.UpdateGdsRegistration(gdsEndpointDescriptor);
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Display results
            Console.WriteLine("Application ID: {0}", applicationId);
        }
    }
}

' Shows how to update an application registration in the GDS, keeping its application ID if possible.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasyOpc.UA
Imports OpcLabs.EasyOpc.UA.AddressSpace
Imports OpcLabs.EasyOpc.UA.Application
Imports OpcLabs.EasyOpc.UA.Application.Extensions
Imports OpcLabs.EasyOpc.UA.Extensions
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Application._IEasyUAClientServerApplication
    Friend Class UpdateGdsRegistration
        Public Shared Sub Main1()

            ' Define which GDS we will work with.
            Dim gdsEndpointDescriptor As UAEndpointDescriptor =
                New UAEndpointDescriptor("opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer") _
                .WithUserNameIdentity("appadmin", "demo")

            ' Obtain the application interface.
            Dim application As EasyUAApplication = EasyUAApplication.Instance

            ' Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString)

            ' Update an application registration in the GDS, keeping its application ID if possible.
            Dim applicationId As UANodeId
            Try
                applicationId = application.UpdateGdsRegistration(gdsEndpointDescriptor)
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try

            ' Display results
            Console.WriteLine("Application ID: {0}", applicationId)
        End Sub
    End Class
End Namespace

COM

// Shows how to update an application registration in the GDS, keeping its application ID if possible.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in Object Pascal (Delphi) on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-OP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

class procedure UpdateGdsRegistration.Main;
var
  Application: TEasyUAApplication;
  ApplicationId: _UANodeId;
  GdsEndpointDescriptor: _UAEndpointDescriptor;
begin
  // Define which GDS we will work with.
  GdsEndpointDescriptor := CoUAEndpointDescriptor.Create;
  GdsEndpointDescriptor.UrlString := 'opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName := 'appadmin';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password := 'demo';

  // Obtain the application interface.
  Application := TEasyUAApplication.Create(nil);

  // Display which application we are about to work with.
  WriteLn('Application URI string: ', Application.GetApplicationElement.ApplicationUriString);

  // Update an application registration in the GDS, keeping its application ID if possible.
  try
    ApplicationId := Application.UpdateGdsRegistration(gdsEndpointDescriptor);
  except
    on E: EOleException do
    begin
      WriteLn(Format('*** Failure: %s', [E.GetBaseException.Message]));
    end;
  end;

  // Display results
  WriteLn('Application ID: ', ApplicationId.ToString);
end;

// Shows how to update an application registration in the GDS, keeping its application ID if possible.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in PHP on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-PHP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

// Define which GDS we will work with.
$GdsEndpointDescriptor = new COM("OpcLabs.EasyOpc.UA.UAEndpointDescriptor");
$GdsEndpointDescriptor->UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->UserName = "appadmin";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->Password = "demo";

// Obtain the application interface.
$Application = new COM("OpcLabs.EasyOpc.UA.Application.EasyUAApplication");

// Display which application we are about to work with.
printf("Application URI string: %s\n", $Application->GetApplicationElement->ApplicationUriString);

// Update an application registration in the GDS, keeping its application ID if possible.
try
{
    $ApplicationId = $Application->UpdateGdsRegistration($GdsEndpointDescriptor);
}
catch (com_exception $e)
{
    printf("*** Failure: %s\n", $e->getMessage());
    exit();
}

// Display results
printf("Application ID: %s\n", $ApplicationId);

REM Shows how to update an application registration in the GDS, keeping its application ID if possible.
REM
REM Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
REM OPC client and subscriber examples in Visual Basic on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VB .
REM Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
REM a commercial license in order to use Online Forums, and we reply to every post.

Private Sub IEasyUAClientServerApplication_UpdateGdsRegistration_Main_Command_Click()
    OutputText = ""
    ' Define which GDS we will work with.
    Dim gdsEndpointDescriptor As New UAEndpointDescriptor
    gdsEndpointDescriptor.UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer"
    gdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName = "appadmin"
    gdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password = "demo"
    
    ' Obtain the application interface
    Dim Application As New EasyUAApplication
    
    ' Display which application we are about to work with.
    OutputText = OutputText & "Application URI string: " & Application.GetApplicationElement.applicationUriString & vbCrLf

    ' Update an application registration in the GDS, keeping its application ID if possible.
    On Error Resume Next
    Dim applicationId As UANodeId
    Set applicationId = Application.UpdateGdsRegistration(gdsEndpointDescriptor)
    If Err.Number <> 0 Then
        OutputText = OutputText & "*** Failure: " & Err.Source & ": " & Err.Description & vbCrLf
        Exit Sub
    End If
    On Error GoTo 0

    ' Display results
    OutputText = OutputText & "Application ID: " & applicationId & vbCrLf
End Sub

Python

# Shows how to update an application registration in the GDS, keeping its application ID if possible.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Application import *
from OpcLabs.EasyOpc.UA.Application.Extensions import *
from OpcLabs.EasyOpc.UA.Extensions import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Define which GDS we will work with.
gdsEndpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer')
gdsEndpointDescriptor = UAEndpointDescriptorExtension.WithUserNameIdentity(gdsEndpointDescriptor,
                                                                           'appadmin', 'demo')

# Obtain the application interface.
application = EasyUAApplication.Instance

# Display which application we are about to work with.
applicationElement = IEasyUAClientServerApplicationExtension.GetApplicationElement(application)
print('Application URI string: ', applicationElement.ApplicationUriString, sep='')

# Update an application registration in the GDS, keeping its application ID if possible.
try:
    print('Updating GDS registration...')
    applicationId = application.UpdateGdsRegistration(gdsEndpointDescriptor)
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

# Display results.
print('Application ID: ', applicationId, sep='')

print()
print('Finished.')

Unregistering from GDS

In order to remove the registration of the current client application from the OPC UA Global DIscovery Server (GDS), call the UnregisterFromGds Method. All existing registrations for the application URI are removed.

This method does not return an error or throw an exception if the application is not currently registered in the GDS.

.NET

// Shows how to delete an application registration from the GDS.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.Extensions;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    class UnregisterFromGds
    {
        public static void Main1()
        {
            // Define which GDS we will work with.
            UAEndpointDescriptor gdsEndpointDescriptor =
                ((UAEndpointDescriptor)"opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer")
                .WithUserNameIdentity("appadmin", "demo");

            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;

            // Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString);

            // Delete an application registration from the GDS.
            try
            {
                application.UnregisterFromGds(gdsEndpointDescriptor);
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }
        }
    }
}

' Shows how to delete an application registration from the GDS.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasyOpc.UA
Imports OpcLabs.EasyOpc.UA.Application
Imports OpcLabs.EasyOpc.UA.Application.Extensions
Imports OpcLabs.EasyOpc.UA.Extensions
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Application._IEasyUAClientServerApplication
    Friend Class UnregisterFromGds
        Public Shared Sub Main1()

            ' Define which GDS we will work with.
            Dim gdsEndpointDescriptor As UAEndpointDescriptor =
                New UAEndpointDescriptor("opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer") _
                .WithUserNameIdentity("appadmin", "demo")

            ' Obtain the application interface.
            Dim application As EasyUAApplication = EasyUAApplication.Instance

            ' Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString)

            ' Delete an application registration from the GDS.
            Try
                application.UnregisterFromGds(gdsEndpointDescriptor)
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try
        End Sub
    End Class
End Namespace

COM

// Shows how to delete an application registration from the GDS.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in Object Pascal (Delphi) on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-OP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

class procedure UnregisterFromGds.Main;
var
  Application: TEasyUAApplication;
  GdsEndpointDescriptor: _UAEndpointDescriptor;
begin
  // Define which GDS we will work with.
  GdsEndpointDescriptor := CoUAEndpointDescriptor.Create;
  GdsEndpointDescriptor.UrlString := 'opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName := 'appadmin';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password := 'demo';

  // Obtain the application interface.
  Application := TEasyUAApplication.Create(nil);

  // Display which application we are about to work with.
  WriteLn('Application URI string: ', Application.GetApplicationElement.ApplicationUriString);

  // Delete an application registration from the GDS.
  try
    Application.UnregisterFromGds(gdsEndpointDescriptor);
  except
    on E: EOleException do
    begin
      WriteLn(Format('*** Failure: %s', [E.GetBaseException.Message]));
    end;
  end;
end;

// Shows how to delete an application registration from the GDS.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in PHP on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-PHP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

// Define which GDS we will work with.
$GdsEndpointDescriptor = new COM("OpcLabs.EasyOpc.UA.UAEndpointDescriptor");
$GdsEndpointDescriptor->UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->UserName = "appadmin";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->Password = "demo";

// Obtain the application interface.
$Application = new COM("OpcLabs.EasyOpc.UA.Application.EasyUAApplication");

// Display which application we are about to work with.
printf("Application URI string: %s\n", $Application->GetApplicationElement->ApplicationUriString);

  // Delete an application registration from the GDS.
try
{
    $Application->UnregisterFromGds($GdsEndpointDescriptor);
}
catch (com_exception $e)
{
    printf("*** Failure: %s\n", $e->getMessage());
    exit();
}

Python

# Shows how to delete an application registration from the GDS.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Application import *
from OpcLabs.EasyOpc.UA.Application.Extensions import *
from OpcLabs.EasyOpc.UA.Extensions import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Define which GDS we will work with.
gdsEndpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer')
gdsEndpointDescriptor = UAEndpointDescriptorExtension.WithUserNameIdentity(gdsEndpointDescriptor,
                                                                           'appadmin', 'demo')

# Obtain the application interface.
application = EasyUAApplication.Instance

# Display which application we are about to work with.
applicationElement = IEasyUAClientServerApplicationExtension.GetApplicationElement(application)
print('Application URI string: ', applicationElement.ApplicationUriString, sep='')

# Delete an application registration from the GDS.
try:
    print('Unregistering from GDS...')
    applicationId = application.UnregisterFromGds(gdsEndpointDescriptor)
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

print()
print('Finished.')

Finding GDS Registrations

In order to find all registrations for the current client application (using its application URI) in the OPC UA Global Discovery Server (GDS), call the FindGdsRegistrations Method. The method returns a dictionary of UAApplicationElement objects with application registration information, keyed by a UANodeId which is the application ID identifying the registration in the GDS.

The identity of the application itself is carried by its application URI, as given by the ApplicationUriString returned by the GetApplicationElement Method. Methods on this interface that manipulate or inspect the GDS registration use the application URI to identify the registration records belonging to this application.

For an example to this method, see: Examples - OPC UA Application - Find all our registrations in GDS.

Getting Application Element

"Application element" is a data structure that contains registration information about an OPC UA application, i.e. how the application is configured to register itself in OPC UA ecosystem. In order to get the registration information for the current client application, call the GetApplicationElement Method.

The data contained the application element is implementation-dependent. For the OPC UA Application component, and OPC UA Client-Server Application Service on the EasyUAClient Class implemented with the OPC Foundation's UA SDK, it is determined by the settings in the UAApplicationManifest Class. In order to modify these parameters, access the ApplicationManifest Property of EasyUAApplication.ApplicationParameters.

For an example to this method, see: Examples - OPC UA Application - Get registration information.

Operations with CM (Certificate Manager)

Some methods in this group work with the OPC UA Global Discovery Server (GDS) in the role of Certificate Manager (CM). Use of the certificate manager can significantly simplify the management of OPC UA security. Only use these methods if your OPC UA setup includes such Global Discovery Server.

Obtaining a New Certificate

In order to begin an asynchronous operation that obtains a new application instance certificate from the certificate manager and stores it for subsequent usage, call the BeginObtainNewCertificate Method.

The operation is asynchronous, because it involves multiple steps, and waiting for a finalization of the request by the Certificate Manager (see the IEasyUACertificateManagementClient.FinishRequest method). End of the operation is handled by the IEasyUAClientServerApplication.EndObtainNewCertificate method. The operation can be cancelled using the IEasyUAClientServerApplication.CancelObtainNewCertificate method.

For a synchronous alternative, see the ObtainNewCertificate Extension Method, with its overloads.

For a task-based asynchronous programming pattern alternative, see the ObtainNewCertificateAsync Extension Method, with its overloads.

The requested certificate subject name might be ignored and/or modified by the Certificate Manager, which means that the obtained certificate can have an unexpected subject name that cannot be predicted. The subject name is, however, used to find the own certificate in the certificate store in any subsequent operations. In order to cope with this issue, QuickOPC applications remember the mapping between the requested and actual certificate subject names. The mappings are persisted in the UAApplication.ini file. This allows the application to find its own instance certificate even if the certificate subject name has been modified by the Certificate Manager.

In some cases, the persistence of subject name mappings (in the UAApplication.ini) is not available (such as when running in a hosted environment with restricted permission that do not allow modification to the file system). For this reason, a certificate can also be found in the certificate store using a "relaxed" method, in which case it is only enough when there is a match in the common name (CN=) of the certificate. This method can be controlled using the new UAClientServerApplicationParameters.RelaxedCertificateSearch Property (defaults to 'true').

.NET

// Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.BaseLib.Security.Cryptography.PkiCertificates;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.Extensions;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    partial class ObtainNewCertificate
    {
        public static void Main1()
        {
            // Define which GDS we will work with.
            UAEndpointDescriptor gdsEndpointDescriptor =
                ((UAEndpointDescriptor)"opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer")
                .WithUserNameIdentity("appadmin", "demo");

            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;

            // Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString);
            
            // Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
            IPkiCertificate certificate;
            try
            {
                certificate = application.ObtainNewCertificate(gdsEndpointDescriptor);
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Display results
            Console.WriteLine("Certificate: {0}", certificate);
        }
    }
}

' Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.BaseLib.Security.Cryptography.PkiCertificates
Imports OpcLabs.EasyOpc.UA
Imports OpcLabs.EasyOpc.UA.Application
Imports OpcLabs.EasyOpc.UA.Application.Extensions
Imports OpcLabs.EasyOpc.UA.Extensions
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Application._IEasyUAClientServerApplication
    Partial Friend Class ObtainNewCertificate
        Public Shared Sub Main1()

            ' Define which GDS we will work with.
            Dim gdsEndpointDescriptor As UAEndpointDescriptor =
                New UAEndpointDescriptor("opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer") _
                .WithUserNameIdentity("appadmin", "demo")

            ' Obtain the application interface.
            Dim application As EasyUAApplication = EasyUAApplication.Instance

            ' Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString)

            ' Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
            Dim certificate As IPkiCertificate
            Try
                certificate = application.ObtainNewCertificate(gdsEndpointDescriptor)
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try

            ' Display results
            Console.WriteLine("Certificate: {0}", certificate)
        End Sub
    End Class
End Namespace

COM

// Shows how to obtain a new application certificate from the certificate manager (GDS),
// and store it for subsequent usage.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in Object Pascal (Delphi) on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-OP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

class procedure ObtainNewCertificate.Main;
var
  Application: TEasyUAApplication;
  ApplicationElement: _UAApplicationElement;
  Certificate: _PkiCertificate;
  GdsEndpointDescriptor: _UAEndpointDescriptor;
  Arguments: _UAObtainCertificateArguments;
begin
  // Define which GDS we will work with.
  GdsEndpointDescriptor := CoUAEndpointDescriptor.Create;
  GdsEndpointDescriptor.UrlString := 'opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName := 'appadmin';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password := 'demo';

  // Obtain the application interface.
  Application := TEasyUAApplication.Create(nil);

  // Display which application we are about to work with.
  ApplicationElement := Application.GetApplicationElement;
  WriteLn('Application URI string: ', Application.GetApplicationElement.ApplicationUriString);

  // Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
  Arguments := CoUAObtainCertificateArguments.Create;
  Arguments.Parameters.GdsEndpointDescriptor := GdsEndpointDescriptor;

  try
    Certificate := Application.ObtainNewCertificate(Arguments);
  except
    on E: EOleException do
    begin
      WriteLn(Format('*** Failure: %s', [E.GetBaseException.Message]));
    end;
  end;

  // Display results
  WriteLn('Certificate: ', (Certificate as _PKICertificate).ToString);
end;

// Shows how to obtain a new application certificate from the certificate manager (GDS),
// and store it for subsequent usage.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in PHP on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-PHP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

// Define which GDS we will work with.
$GdsEndpointDescriptor = new COM("OpcLabs.EasyOpc.UA.UAEndpointDescriptor");
$GdsEndpointDescriptor->UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->UserName = "appadmin";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->Password = "demo";

// Obtain the application interface.
$Application = new COM("OpcLabs.EasyOpc.UA.Application.EasyUAApplication");

// Display which application we are about to work with.
$ApplicationElement = $Application->GetApplicationElement;
printf("Application URI string: %s\n", $Application->GetApplicationElement->ApplicationUriString);

// Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
$Arguments = new COM("OpcLabs.EasyOpc.UA.Application.UAObtainCertificateArguments");
$Arguments->Parameters->GdsEndpointDescriptor = $GdsEndpointDescriptor;

try
{
    $Certificate = $Application->ObtainNewCertificate($Arguments);
}
catch (com_exception $e)
{
    printf("*** Failure: %s\n", $e->getMessage());
    exit();
}

// Display results
printf("Certificate: %s\n", $Certificate);

REM Shows how to obtain a new application certificate from the certificate manager (GDS),
REM and store it for subsequent usage.
REM
REM Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
REM OPC client and subscriber examples in Visual Basic on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VB .
REM Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
REM a commercial license in order to use Online Forums, and we reply to every post.

Private Sub IEasyUAClientServerApplication_ObtainNewCertificate_Main_Command_Click()
    OutputText = ""
    
    ' Define which GDS we will work with.
    Dim gdsEndpointDescriptor As New UAEndpointDescriptor
    gdsEndpointDescriptor.UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer"
    gdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName = "appadmin"
    gdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password = "demo"
    
    ' Obtain the application interface
    Dim Application As New EasyUAApplication
    
    ' Display which application we are about to work with.
    OutputText = OutputText & "Application URI string: " & Application.GetApplicationElement.applicationUriString & vbCrLf

    ' Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
    Dim arguments As New UAObtainCertificateArguments
    Set arguments.Parameters.gdsEndpointDescriptor = gdsEndpointDescriptor
    
    On Error Resume Next
    Dim certificate As PkiCertificate
    Set certificate = Application.ObtainNewCertificate(arguments)
    If Err.Number <> 0 Then
        OutputText = OutputText & "*** Failure: " & Err.Source & ": " & Err.Description & vbCrLf
        Exit Sub
    End If
    On Error GoTo 0

    ' Display results
    OutputText = OutputText & "Certificate: " & certificate & vbCrLf
End Sub

Rem Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
Rem
Rem Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
Rem OPC client and subscriber examples in VBScript on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBScript .
Rem Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
Rem a commercial license in order to use Online Forums, and we reply to every post.

Option Explicit

' Define which GDS we will work with.
Dim GdsEndpointDescriptor: Set GdsEndpointDescriptor = CreateObject("OpcLabs.EasyOpc.UA.UAEndpointDescriptor")
GdsEndpointDescriptor.UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer"
GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName = "appadmin"
GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password = "demo"

' Obtain the application interface.
Dim Application: Set Application = CreateObject("OpcLabs.EasyOpc.UA.Application.EasyUAApplication")

' Display which application we are about to work with.
Dim ApplicationElement: Set ApplicationElement = Application.GetApplicationElement
WScript.Echo "Application URI string: " & Application.GetApplicationElement.ApplicationUriString

Rem Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
Dim Arguments: Set Arguments = CreateObject("OpcLabs.EasyOpc.UA.Application.UAObtainCertificateArguments")
Set Arguments.Parameters.GdsEndpointDescriptor = GdsEndpointDescriptor
On Error Resume Next
Dim Certificate: Set Certificate = Application.ObtainNewCertificate(Arguments)
If Err.Number <> 0 Then
    WScript.Echo "*** Failure: " & Err.Source & ": " & Err.Description
    WScript.Quit
End If
On Error Goto 0

' Display results
WScript.Echo "Certificate: " & Certificate

Python

# Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent
# usage.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Application import *
from OpcLabs.EasyOpc.UA.Application.Extensions import *
from OpcLabs.EasyOpc.UA.Extensions import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Define which GDS we will work with.
gdsEndpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer')
gdsEndpointDescriptor = UAEndpointDescriptorExtension.WithUserNameIdentity(gdsEndpointDescriptor,
                                                                           'appadmin', 'demo')

# Obtain the application interface.
application = EasyUAApplication.Instance

# Display which application we are about to work with.
applicationElement = IEasyUAClientServerApplicationExtension.GetApplicationElement(application)
print('Application URI string: ', applicationElement.ApplicationUriString, sep='')

# Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
try:
    print('Obtaining new certificate...')
    certificate = IEasyUAClientServerApplicationExtension.ObtainNewCertificate(application, gdsEndpointDescriptor)
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

# Display results.
print('Certificate: ', certificate, sep='')

print()
print('Finished.')

This method can also be provided a callback, in form of the IProgress Interface, through which it reports its progress.

.NET

// Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage,
// with progress reporting.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.BaseLib.Security.Cryptography.PkiCertificates;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.Extensions;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    partial class ObtainNewCertificate
    {
        public static void Progress()
        {
            // Define which GDS we will work with.
            UAEndpointDescriptor gdsEndpointDescriptor = 
                ((UAEndpointDescriptor)"opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer")
                .WithUserNameIdentity("appadmin", "demo");

            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;

            // Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString);

            // Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
            IPkiCertificate certificate;
            try
            {
                certificate = application.ObtainNewCertificate(gdsEndpointDescriptor,
                    new Progress<string>(s => Console.WriteLine("Progress: {0}", s)));
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Display results
            Console.WriteLine("Certificate: {0}", certificate);
        }
    }
}

' Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage,
' with progress reporting.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.BaseLib.Security.Cryptography.PkiCertificates
Imports OpcLabs.EasyOpc.UA
Imports OpcLabs.EasyOpc.UA.Application
Imports OpcLabs.EasyOpc.UA.Application.Extensions
Imports OpcLabs.EasyOpc.UA.Extensions
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Application._IEasyUAClientServerApplication
    Partial Friend Class ObtainNewCertificate
        Public Shared Sub Progress()

            ' Define which GDS we will work with.
            Dim gdsEndpointDescriptor As UAEndpointDescriptor =
                New UAEndpointDescriptor("opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer") _
                .WithUserNameIdentity("appadmin", "demo")

            ' Obtain the application interface.
            Dim application As EasyUAApplication = EasyUAApplication.Instance

            ' Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString)

            ' Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
            Dim certificate As IPkiCertificate
            Try
                certificate = application.ObtainNewCertificate(gdsEndpointDescriptor,
                    New Progress(Of String)(Sub(s) Console.WriteLine("Progress: {0}", s)))
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try

            ' Display results
            Console.WriteLine("Certificate: {0}", certificate)
        End Sub
    End Class
End Namespace

Python

# Shows how to obtain a new application certificate from the certificate manager (GDS), and store it for subsequent
# usage, with progress reporting.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from System import *
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Application import *
from OpcLabs.EasyOpc.UA.Application.Extensions import *
from OpcLabs.EasyOpc.UA.Extensions import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Define which GDS we will work with.
gdsEndpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer')
gdsEndpointDescriptor = UAEndpointDescriptorExtension.WithUserNameIdentity(gdsEndpointDescriptor,
                                                                           'appadmin', 'demo')

# Obtain the application interface.
application = EasyUAApplication.Instance

# Display which application we are about to work with.
applicationElement = IEasyUAClientServerApplicationExtension.GetApplicationElement(application)
print('Application URI string: ', applicationElement.ApplicationUriString, sep='')

# Obtain a new application certificate from the certificate manager (GDS), and store it for subsequent usage.
try:
    print('Obtaining new certificate...')
    certificate = IEasyUAClientServerApplicationExtension.ObtainNewCertificate(application,
        gdsEndpointDescriptor,
        Progress[String](Action[String](lambda s: print('Progress: ', s, sep=''))))
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

# Display results.
print()
print('Certificate: ', certificate, sep='')

print()
print('Finished.')

If you are dealing with multiple certificate types, you can specify the Id of the certificate type for the new certificate using the CertificateTypeId Property in the Parameters Property of UAObtainCertificateArguments Class object passed to the method. For obtaining the available certificate type Ids, see "Listing Certificate Type Ids" below.

Using the UpdateTrustedPeerCertificates Property (defaults to true), you can control whether the trusted peers certificate store will also be updated.

Refreshing Trust Lists

In order to retrieve the current trust lists for the application from the certificate manager, and refresh own certificate stores accordingly, call the RefreshTrustLists Method.

The operation first updates the application's registration in the GDS, before retrieving the trust lists from the certificate manager and adding them to the certificate stores

.NET

// Shows how to refresh own certificate stores using current trust lists for the application from the certificate manager.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.Application;
using OpcLabs.EasyOpc.UA.Application.Extensions;
using OpcLabs.EasyOpc.UA.Extensions;
using OpcLabs.EasyOpc.UA.Gds;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UADocExamples.Application._IEasyUAClientServerApplication
{
    class RefreshTrustLists
    {
        public static void Main1()
        {
            // Define which GDS we will work with.
            UAEndpointDescriptor gdsEndpointDescriptor =
                ((UAEndpointDescriptor)"opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer")
                .WithUserNameIdentity("appadmin", "demo");

            // Obtain the application interface.
            EasyUAApplication application = EasyUAApplication.Instance;

            // Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString);

            // Refresh own certificate stores using current trust lists for the application from the certificate manager.
            UATrustListMasks refreshedTrustLists;
            try
            {
                refreshedTrustLists = application.RefreshTrustLists(gdsEndpointDescriptor);
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Display results
            Console.WriteLine("Refreshed trust lists: {0}", refreshedTrustLists);
        }
    }
}

' Shows how to refresh own certificate stores using current trust lists for the application from the certificate manager.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasyOpc.UA
Imports OpcLabs.EasyOpc.UA.Application
Imports OpcLabs.EasyOpc.UA.Application.Extensions
Imports OpcLabs.EasyOpc.UA.Extensions
Imports OpcLabs.EasyOpc.UA.Gds
Imports OpcLabs.EasyOpc.UA.OperationModel

Namespace Application._IEasyUAClientServerApplication
    Friend Class RefreshTrustLists
        Public Shared Sub Main1()

            ' Define which GDS we will work with.
            Dim gdsEndpointDescriptor As UAEndpointDescriptor =
                New UAEndpointDescriptor("opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer") _
                .WithUserNameIdentity("appadmin", "demo")

            ' Obtain the application interface.
            Dim application As EasyUAApplication = EasyUAApplication.Instance

            ' Display which application we are about to work with.
            Console.WriteLine("Application URI string: {0}",
                application.GetApplicationElement().ApplicationUriString)

            ' Refresh own certificate stores using current trust lists for the application from the certificate manager.
            Dim refreshedTrustLists As UATrustListMasks
            Try
                refreshedTrustLists = application.RefreshTrustLists(gdsEndpointDescriptor)
            Catch uaException As UAException
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException.Message)
                Exit Sub
            End Try

            ' Display results
            Console.WriteLine("Refreshed trust lists: {0}", refreshedTrustLists)
        End Sub
    End Class
End Namespace

COM

// Shows how to refresh own certificate stores using current trust lists
// for the application from the certificate manager.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in Object Pascal (Delphi) on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-OP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

class procedure RefreshTrustLists.Main;
var
  Application: TEasyUAApplication;
  GdsEndpointDescriptor: _UAEndpointDescriptor;
  RefreshedTrustLists: UATrustListMasks;
begin
  // Define which GDS we will work with.
  GdsEndpointDescriptor := CoUAEndpointDescriptor.Create;
  GdsEndpointDescriptor.UrlString := 'opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName := 'appadmin';
  GdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password := 'demo';

  // Obtain the application interface.
  Application := TEasyUAApplication.Create(nil);

  // Display which application we are about to work with.
  WriteLn('Application URI string: ', Application.GetApplicationElement.ApplicationUriString);

  // Refresh own certificate stores using current trust lists for the application from the certificate manager.
  try
    RefreshedTrustLists := Application.RefreshTrustLists(gdsEndpointDescriptor, True);
  except
    on E: EOleException do
    begin
      WriteLn(Format('*** Failure: %s', [E.GetBaseException.Message]));
      Exit;
    end;
  end;

  // Display results
  WriteLn('Refreshed trust lists: ', RefreshedTrustLists);
end;

// Shows how to refresh own certificate stores using current trust lists
// for the application from the certificate manager.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in PHP on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-PHP .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

// Define which GDS we will work with.
$GdsEndpointDescriptor = new COM("OpcLabs.EasyOpc.UA.UAEndpointDescriptor");
$GdsEndpointDescriptor->UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->UserName = "appadmin";
$GdsEndpointDescriptor->UserIdentity->UserNameTokenInfo->Password = "demo";

// Obtain the application interface.
$Application = new COM("OpcLabs.EasyOpc.UA.Application.EasyUAApplication");

// Display which application we are about to work with.
printf("Application URI string: %s\n", $Application->GetApplicationElement->ApplicationUriString);

// Refresh own certificate stores using current trust lists for the application from the certificate manager.
try
{
    $RefreshedTrustLists = $Application->RefreshTrustLists($GdsEndpointDescriptor, true);
}
catch (com_exception $e)
{
    printf("*** Failure: %s\n", $e->getMessage());
    exit();
}

// Display results
printf("Refreshed trust lists: %s\n", $RefreshedTrustLists);

REM Shows how to refresh own certificate stores using current trust lists
REM for the application from the certificate manager.
REM
REM Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
REM OPC client and subscriber examples in Visual Basic on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VB .
REM Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
REM a commercial license in order to use Online Forums, and we reply to every post.

Private Sub IEasyUAClientServerApplication_RefreshTrustLists_Main_Command_Click()
    OutputText = ""
    
    ' Define which GDS we will work with.
    Dim gdsEndpointDescriptor As New UAEndpointDescriptor
    gdsEndpointDescriptor.UrlString = "opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer"
    gdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.UserName = "appadmin"
    gdsEndpointDescriptor.UserIdentity.UserNameTokenInfo.Password = "demo"
    
    ' Obtain the application interface
    Dim Application As New EasyUAApplication
    
    ' Display which application we are about to work with.
    OutputText = OutputText & "Application URI string: " & Application.GetApplicationElement.applicationUriString & vbCrLf

    ' Refresh own certificate stores using current trust lists for the application from the certificate manager.
    On Error Resume Next
    Dim refreshedTrustLists As UATrustListMasks
    refreshedTrustLists = Application.RefreshTrustLists(gdsEndpointDescriptor, True)
    If Err.Number <> 0 Then
        OutputText = OutputText & "*** Failure: " & Err.Source & ": " & Err.Description & vbCrLf
        Exit Sub
    End If
    On Error GoTo 0

    ' Display results
    OutputText = OutputText & "Refreshed trust lists: " & refreshedTrustLists & vbCrLf
End Sub

Python

# Shows how to refresh own certificate stores using current trust lists for the application from the certificate
# manager.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc

# Import .NET namespaces.
from System import *
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.Application import *
from OpcLabs.EasyOpc.UA.Application.Extensions import *
from OpcLabs.EasyOpc.UA.Extensions import *
from OpcLabs.EasyOpc.UA.Gds import *
from OpcLabs.EasyOpc.UA.OperationModel import *


# Define which GDS we will work with.
gdsEndpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer')
gdsEndpointDescriptor = UAEndpointDescriptorExtension.WithUserNameIdentity(gdsEndpointDescriptor,
                                                                           'appadmin', 'demo')

# Obtain the application interface.
application = EasyUAApplication.Instance

# Display which application we are about to work with.
applicationElement = IEasyUAClientServerApplicationExtension.GetApplicationElement(application)
print('Application URI string: ', applicationElement.ApplicationUriString, sep='')

# Refresh own certificate stores using current trust lists for the application from the certificate manager.
try:
    print('Refreshing trust lists...')
    refreshedTrustLists = IEasyUAClientServerApplicationExtension.RefreshTrustLists(application, gdsEndpointDescriptor)
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

# Display results.
print('Refreshed trust lists: ', Enum.Format(UATrustListMasks, refreshedTrustLists, 'G'), sep='')

print()
print('Finished.')

Listing Certificate Type Ids

The Certificate Manager may offer multiple different types of certificates for any given purpose (such as application instance certificates). This is because different servers you connect to may support different security policies, and those security policies may differ in the type of certificate they are associated with. The ListCertificateTypeElements Method retrieves node elements for of certificate types available for a given application store kind.

The obtained certificate type Id can be used when obtaining a new certificate from the GDS, described above.

Working with Multiple Certificates

In most cases, an OPC UA application needs just application instance certificates. In some advances scenarios, however, the OPC UA client may have more instance certificates, and use different certificates with different server endpoints. This may be necessary when the OPC UA server have conflicting requirement for the certificate parameters, or when they are configured to trust different certificate authorities (CAs).

For this reason, many methods on the IEasyUAClientServerApplication Interface have a string argument called certificate sub-Id, which distinguishes the different certificates inside the application (or, there is a CertificateSubId Property when arguments object is being passed to the method, such as with UAObtainNewCertificateArguments Class). The default application instance certificate is signified by a certificate sub-Id that is an empty string. There are extension methods that allow you to omit the certificate sub-Id argument in most cases, and they pass in an empty string for the certificate sub-Id.

The certificates in the certificate stores are distinguished by a combination of their common name, and the certificate sub-Id. For non-default sub-ids, QuickOPC uses a special syntax which appends the certificate sub-id in double parentheses to the common name. For example, assume that the default certificate subject name for the application is

    CN=My Experimental UA Application

If you specify a certificate sub-id using the string "alt" for the application instance certificate, the certificate subject name becomes 

    CN=My Experimental UA Application ((alt))

If you want QuickOPC to use specific application instance certificate when connecting to an OPC UA server, set the CertificateSubId Property in the UAEndpointDescriptor you are passing to the operation. The value of this property should be the sub-Id of the certificate you want to be used for the connection to the server. See also OPC UA Server Endpoints.

In order to obtain a set (collection) of certificate sub-ids of all application certificates in the certificate store, call the ListCertificateSubIds Method. You can also obtain a dictionary of certificate subject names corresponding to all application certificate sub-ids, using the GetCertificateSubjectNameDictionary Method.

Application State Persistence

The state of the OPC UA application component (such as the application IDs obtained from the GDS endpoints, and subject names of certificates obtained from the GDS) is persisted on the disk. This means that when the application is terminated and then started again, the state information from the previous run will be reused. The state is persisted in the UAApplication.ini file.

Windows Desktop Applications

In Windows desktop applications (Windows Forms and WPF project types), you have additional functionality at your disposal for managing the OPC UA Application.

You can invoke the Administer OPC UA Application Dialog either using the EasyUAFormsApplication Class, or with the UIAdministerApplication Method.

The EasyUAFormsApplication Class also has the AddToSystemMenu Method, which adds items related to the OPC UA application to the system menu of the given form. The method adds the "Administer OPC UA Application" command to the system menu of the form, allowing the user to view and manage the certificate trust, and the own application certificate. The system menu is accessed by clicking in the very top left corner of the window caption bar, or from the keyboard using Alt+Space. You would typically add this to the system menu of the application's main form, because administering the OPC UA application is a global action that affects the application as a whole.